PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/pascal/bgiclip.com/CLIP.DOC

Text File | 1990-11-07 | 12.1 KB | 283 lines

===========================================================================

                                    CLIP

                             by Peter Donnelly
                              1301 Ryan Street
                                Victoria BC
                               Canada V8T 4Y8

===========================================================================

INTRODUCTION
------------

The Borland Graphical Interface contains an easy-to-use procedure,
PutImage, for displaying complex images on a portion of the screen.
However, the Turbo C or Pascal programmer faces the difficulty of getting
the image into memory in the first place - that is, of drawing it.

CLIP is a bridge between powerful commercial painting programs (such as
Paintbrush and Deluxe Paint II Enhanced) and the BGI. It lets you "clip"
images of any size (up to the 64K limit imposed by PutImage) from PCX files
in EGA and VGA high resolution, and puts these images in files that can be
used by your C or Pascal routines with a minimum of effort.


OPERATION
---------

The program is very simple to use. First create a PCX graphics file in
16-color 640x200, 640x350, or 640x480 resolution, using a painting or
screen-capture program. (If your software doesn't directly support the PCX
format, it may include a conversion program that does.) Then run CLIP with
the pathname of the graphics file on the command line; don't include the
".PCX" part.

By default the program will come up in 640x480 resolution if your system
supports it, but you can override this default by entering "/e" on the
command line after the PCX file name, in which case the display mode will
be 640x350 and only EGA palette information will be produced (more on this
below).

Now, with the mouse, point to one corner of the image you wish to save.
Hold down the left button and drag the mouse to create a frame around the
image. The area you are defining includes the pixels covered by the frame
lines, so that you can work right to the edge of the screen.

When you release the button, you are prompted to enter a name for the image
file. Type the file name and press <Enter>, or abort with <Esc>. You may
use any file name except one with the extension ".PAL".

If the image is too large for the BGI PutImage procedure, a bell sounds and
you are not allowed to save. The size limit is about 58 percent of the
screen in EGA mode or about 42 percent in VGA. If you want to save the
entire screen, you can of course do so in chunks; but a better way is to
get PCXPAS.ZIP, which contains a Turbo Pascal unit for the very quick
display of full-screen PCX files in most formats.

By default the co-ordinates of the mouse are shown at the upper right
corner of the screen. This information can be useful for cutting images
exactly to size, especially if you have made a note of the desired
boundaries while working in the magnified mode of your painting program. If
you wish to cut an image in this corner of the screen, press <F1> to toggle
off the display of co-ordinates.

Continue saving images from the screen until you're done; then press
<Alt-X> or <F10> to exit.


USING CLIP IMAGES IN TURBO PASCAL AND TURBO C
---------------------------------------------

The data structure used by Borland's image-manipulating procedures and
functions is the same in both Turbo Pascal and Turbo C, and CLIP's
output files are equally usable with either language. The examples in this
section will be in Pascal.

The disk file created by CLIP to store an image takes exactly the same
form as the data structure created by the Turbo GetImage procedure and used
by PutImage. It is an untyped file.

The first two words in the file store the width and height respectively of
the image (counting from zero: an image of "1 by 1" is actually 2 by 2).
The PutImage procedure uses these figures to set up the image properly, and
they are also used by ImageSize to calculate the storage needed for the
image. The BGI does not use data compression; a blank image occupies as
much storage space as a complex image of the same dimensions.

Here is a simple routine to import an image from a file and display it at
the current pointer.

  var    BitMap: Pointer;
         f: file;

  Begin
    Assign(f, 'MYIMAGE.IM');
    Reset(f, 1);
    GetMem(BitMap, FileSize(f));
    BlockRead(f, BitMap^, FileSize(f));
    PutImage(GetX, GetY, BitMap^, CopyPut);
  End;

For a program that uses multiple images, it may be convenient to group all
the images together in a single data file. It is easy to do so with the DOS
Copy command. For example, to create a file "CHESSMEN" containing all the
pieces:

  COPY KING/B + QUEEN + BISHOP + KNIGHT + ROOK + PAWN CHESSMEN

Note the "/B" argument after the first filename. Do not omit this; it is
essential so that DOS treats all the files as binary and does not truncate
any on encountering a Control-Z.

Obviously it is up to the programmer to ensure that the file-reading
routines take into account the number of bytes occupied by each image. If
the file contains images of different sizes that are to be stored
dynamically as they are imported, you can use the ImageSize function to
determine how much memory to allocate for each image:

  var   Width, Height, Size: word;
        BitMap: pointer;
        f: file;

  Reset(f, 1);
  BlockRead(f, Width, 2);               { Get dimensions from header }
  BlockRead(f, Height, 2);
  Size:= ImageSize(0, 0, Width, Height);
  GetMem(BitMap, Size);
  Seek(f, FilePos(f) - 4);              { Back up }
  BlockRead(f, Bitmap^, Size);          { Get whole image }

This routine has the great advantage that you can alter the size of any of
the component images in the file without having to change program code.


INCORPORATING PALETTE CHANGES
-----------------------------

Whenever you save an image file, CLIP automatically creates a palette
file with the same name and the extension ".PAL". If CLIP is running in
EGA (350-line) mode, this is simply an untyped 17-byte file containing a
PaletteType record. For the VGA, it is an array of the RGB values for each
of the 16 palette entries, or 48 bytes in all.

If you are working in 350-line mode on the VGA, the program presumes that
you want only EGA palette data. If you want the full VGA information, you
can load the file in 480-line mode; the resulting distortion will make no
difference if the clipped images are ultimately to be displayed in their
original 350-line format.

For the EGA, you can easily import saved palette values into your own
program by BlockReading the palette file into a PaletteType variable. It is
then simply a matter of passing that variable into SetAllPalette. (Of
course, in many cases it may be preferable to hard-code the palette values,
which can be examined with DEBUG.)

For the VGA, things are a bit more complicated. Here you have to make these
declarations:

   type    RGBrec = record
                      redval, greenval, blueval: byte;
                    end;

   var     RGBpalette: array[0..15] of RGBrec;

Now BlockRead the palette file into RGBpalette. From here the data can be
passed into Turbo's SetRGBPalette procedure; but first you have to make
sure that the palette entries are pointing to the registers you are
modifying. (In the VGA, the 16 palette entries don't contain color values;
they contain the numbers of color registers, which in turn hold the actual
colors.) By default the palette points to registers 0-5, 20, 7, and 56-63,
which contain the standard EGA colors. You can either modify these
registers or else use SetPalette to put the numbers 0-15 in the palette,
then modify registers 0-15 with SetRGBPalette.

Files of 640x200 resolution are a special case. If you want to display
images in the BGI "EGALo" format, only the 16 default colors are available,
so it is unlikely you will want any palette information; in any case, the
.PAL file produced by CLIP in its EGA mode will be of no use since the
palette system is completely different in 200-line and 350-line modes. If
you want the full VGA palette data for "VGALo" format, you must create the
image in CLIP's 480-line mode. Again, the distortion will make no
difference in the final product.


LINKING DATA INTO THE .EXE FILE
-------------------------------

For the sake of tidiness you may want to incorporate image and palette data
in the executable file itself rather than keeping it in separate files.
Turbo Pascal makes this easy.

Suppose you have an image of an apple in the file MYAPPLE.IM. First convert
this to an object file with Borland's BINOBJ program (distributed with
Turbo Pascal) thus:

  BINOBJ MYAPPLE.IM APPLE GETAPPLE

There are three arguments on the command line. The first is the source
file, the second is the destination file (.OBJ is assumed), and the third
is the public declaration or interface of the object file. You are creating
APPLE.OBJ, which contains the public declaration GetApple.

Now, in your Pascal program, you declare a dummy "procedure" using the
public name of the data, and link in the object file:

  procedure GetApple; external;
  {$L APPLE.OBJ}

Finally, you declare a pointer variable and assign it the address of the
dummy procedure:

  var   AppleImage: pointer;

  AppleImage:= @GetApple;

And when you want to display the image:

  PutImage(GetX, GetY, AppleImage^, CopyPut);

Although linked data is convenient, remember that it takes up memory space
for the life of the program, whereas data from files can be read into
dynamic memory and discarded when no longer needed. If memory is in short
supply and an image only has to be written to the screen once, a separate
data file is probably the best choice.


COPYRIGHT NOTICE
----------------

CLIP was produced with Turbo Pascal and Turbo Assembler, both copyrighted
programs of Borland International.

===========================================================================


         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 2,000+ disks in the library, call or write

                           Public (software) Library
                               P.O.Box 35705 - F
                            Houston, TX 77235-5705

                                1-800-2424-PSL
                             MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394

                          PsL also has an outstanding
                          catalog for the Macintosh.